home *** CD-ROM | disk | FTP | other *** search
/ The PC-SIG Library 10 / The PC-Sig Library - Shareware for the IBM PC and Compatibles (PC-SIG)(Tenth Edition Disks 1-2804)(1991).iso / PC_SIGCD / 14 / 5 / DISK1459.ZIP / TAP.DOC < prev    next >
Text File  |  1989-02-22  |  14KB  |  285 lines
  1.                        Welcome to Turbo Apprentice
  2.  
  3.                           (Documentation v1.0)
  4.  
  5.  
  6. Turbo Apprentice is distributed as shareware by Cypress Systems, Inc.  If
  7. you use Turbo Apprentice, please send a $15 registration fee to:
  8.  
  9.                     Cypress Systems, Inc.
  10.                     11693 San Vicente Blvd., Suite 175
  11.                     Los Angeles, CA  90049
  12.  
  13. Please include your serial number with your registration fee.  If you have
  14. any questions, comments or suggestions, please feel free to include them
  15. with your registration fee or call us at (213) 207-3938 between 9:00 am and
  16. 5:00 pm (Pacific Standard Time) Monday through Friday.  We can also be
  17. reached on BIX (as cypress) or on CompuServe (as 71631,735).
  18.  
  19. You are free to distribute Turbo Apprentice as long as you do not charge
  20. a fee for doing so.  Please include the following files:
  21.  
  22.             TAP.DOC                            TAP.ARC
  23.             TAPINST.EXE           or
  24.             TAP.EXE
  25.  
  26.  
  27.  
  28. Introduction
  29. ------------
  30.  
  31. Turbo Apprentice is a Terminate and Stay Resident utility which enables
  32. you to extend Turbo Pascal's context sensitive help system to include
  33. reference information for your own units, procedures and functions.
  34. Apprentice works by creating an index file for each unit used by your
  35. program.  Once the index files are completed, pop-up help for any
  36. procedure or function used by your program is a key-stroke away.
  37.  
  38. Turbo Apprentice requires an IBM PC/XT/AT, PS/2 or 100% compatible, MS-DOS
  39. 2.0 or higher, a hard disk drive, and Turbo Pascal 4.0 or higher.
  40.  
  41.  
  42.  
  43. Installation
  44. ------------
  45.  
  46. To install Turbo Apprentice:
  47.  
  48.   - Copy the files TAPINST.EXE and        Example:
  49.     TAP.EXE to the same subdirectory
  50.     on your hard disk.                    C>COPY A:TAP*.EXE C:\TURBO5\TAP
  51.  
  52.   - Change to that directory and run      C>CD \TURBO5\TAP
  53.     TAPINST.EXE.                          C>TAPINST
  54.  
  55.   - TAPINST enables you to install a Primary File, a Help Directory, a
  56.     list of Unit Directories, a list of Include Directories, and a Color
  57.     Set into the TAP.EXE file.  Of these, it is ESSENTIAL that you
  58.     provide the Help Directory and Unit/Include Directory lists.
  59.  
  60.     Here is an explanation of what each item means:
  61.  
  62.     Primary File        - The full path name you provide here will be used
  63.                           as the default primary program file each time
  64.                           TAP.EXE is run.
  65.     Help Directory      - The directory path you provide here tells
  66.                           Apprentice where to keep the index files it
  67.                           will create.
  68.     Unit Directories    - The list of directories you provide here tells
  69.                           Apprentice where to look for your unit source
  70.                           files.  This list should be identical to the
  71.                           "Unit Directories" you must provide for Turbo
  72.                           Pascal.
  73.     Include Directories - The list of directories you provide here tells
  74.                           Apprentice where to look for your include files.
  75.                           This list should be identical to the "Include
  76.                           Directories" you must provide for Turbo Pascal.
  77.     Colors              - The color set you choose will be the one used
  78.                           by TAP.EXE.  The various sets correspond to those
  79.                           used by Turbo Pascal 4.0 and 5.0.
  80.  
  81.   - Once you have set the various TAPINST options, choose "Quit/save" and
  82.     you will be prompted to verify saving the changes to TAP.EXE.  Once
  83.     you have installed any options into TAP.EXE, you can change them again
  84.     by running TAPINST.EXE at any time.
  85.  
  86.  
  87.  
  88. Using Turbo Apprentice
  89. ----------------------
  90.  
  91.   To load Apprentice into memory, simply enter "TAP" at the DOS prompt.
  92.   Apprentice will display a message telling you if it loaded successfully,
  93.   and take you back to the DOS prompt.  You may now invoke Turbo Pascal,
  94.   and Apprentice will be waiting in the background for you.  Since
  95.   Apprentice is virtually useless alone, you will want to remove it from
  96.   memory after you leave Turbo Pascal.  To do this, enter "TAP /r" at
  97.   the DOS prompt.
  98.  
  99.  
  100.   Preparing your source files:
  101.  
  102.   The quickest way to get Apprentice up and running is to make no changes
  103.   to your source files.  Using this approach means that when you call upon
  104.   Apprentice to provide pop-up reference information on a procedure or
  105.   function, it will display only the procedure or function header (the name
  106.   and parameter information for that procedure or function) and the name
  107.   of the unit it is in.  This may be enough for most of your purposes.
  108.  
  109.   However, Apprentice does provide a way for you to view any comments you
  110.   may wish to include along with the procedure or function header.  By
  111.   including your comments in your source file directly following the
  112.   procedure or function header declaration, and surrounding the comments
  113.   by {* and *} or (** and **), you will be telling Apprentice to include
  114.   those comments in the help window.  For example, the following piece of
  115.   code:
  116.  
  117.     procedure GetAddress(var theAddress : string);
  118.  
  119.     {*
  120.     This procedure prompts the user for the employee's address and returns
  121.     the address in the parameter "theAddress".
  122.     *}
  123.  
  124.   will cause the following information to be popped-up:
  125.  
  126.   +------------------------------ Apprentice ------------------------------+
  127.   | Unit: Entry                                                            |
  128.   |                                                                        |
  129.   | procedure GetAddress(var theAddress : string);                         |
  130.   |                                                                        |
  131.   |                                                                        |
  132.   | This procedure prompts the user for the employee's address and returns |
  133.   | the address in the parameter "theAddress".                             |
  134.   |                                                                        |
  135.   |                                                                        |
  136.   |                                                                        |
  137.   +------------------------------------------------------------------------+
  138.  
  139.   NOTE:  For procedure and function declarations that appear in the
  140.          INTERFACE section of a unit, you must include your comments with
  141.          the interface declaration if you want them to be recognized by
  142.          Apprentice.
  143.  
  144.   An additional feature of Apprentice is its "hot keywords".  In the above
  145.   help window, the unit name "Entry" would be highlighted as a hot keyword.
  146.   Pressing <Enter> while "Entry" is highlighted would bring up the help
  147.   information for the Entry unit.  (Unit help information is provided auto-
  148.   matically by Apprentice).
  149.  
  150.   You can include hot keyword references to other units, procedures and
  151.   functions in your own comments by surrounding each keyword with the
  152.   vertical bar character (|).  Here's an example:
  153.  
  154.     procedure GetAddress(var theAddress : string);
  155.  
  156.     {*
  157.     This procedure prompts the user for the employee's address and returns
  158.     the address in the parameter "theAddress".
  159.  
  160.     See also:  |GetCity|   |GetState|   |GetZip|
  161.     *}
  162.  
  163.   would cause the following information to be popped-up:
  164.  
  165.   +------------------------------ Apprentice ------------------------------+
  166.   | Unit: Entry                                                            |
  167.   |                                                                        |
  168.   | procedure GetAddress(var theAddress : string);                         |
  169.   |                                                                        |
  170.   |                                                                        |
  171.   | This procedure prompts the user for the employee's address and returns |
  172.   | the address in the parameter "theAddress".                             |
  173.   |                                                                        |
  174.   | See also:  GetCity   GetState   GetZip                                 |
  175.   |                                                                        |
  176.   +------------------------------------------------------------------------+
  177.  
  178.   where "Entry", "GetCity", "GetState" and "GetZip" would all be displayed
  179.   as hot keywords.
  180.  
  181.  
  182.   The Turbo Apprentice menu:
  183.  
  184.   To bring up the Apprentice menu while in the Turbo Pascal editor, press
  185.   <Alt><A>.  The Apprentice menu contains four options:  Primary file,
  186.   Directories, Make index file(s), and Build index file(s).
  187.  
  188.   Here is an explanation of what each item will do:
  189.  
  190.   Primary file        - The full path name you provide here will be used as
  191.                         the primary file when generating index files.  When
  192.                         Apprentice attempts to provide pop-up help, this
  193.                         file's corresponding index file will be used as
  194.                         the primary index file.
  195.   Directories         - Choosing this option will display the Help
  196.                         Directory, Unit Directories and Include Directories
  197.                         that were installed into the currently running copy
  198.                         of TAP.EXE.
  199.   Make index file(s), - Choosing these options will tell Apprentice to begin
  200.   Build index file(s)   generating the index files, in which are kept your
  201.                         procedure and function names and their positions in
  202.                         your source files.  One index file (with the file
  203.                         extension ".TAP") is created for each unit that your
  204.                         program uses (directly or indirectly), and it is
  205.                         kept in the Help Directory you have specified.  If
  206.                         an error occurs during index file generation, the
  207.                         process will be aborted.  The best way to avoid this
  208.                         is to make sure all of your source code compiles
  209.                         with Turbo Pascal before trying to make or build
  210.                         with Apprentice.  NOTE:  You must save the file
  211.                         currently being edited for Apprentice to recognize
  212.                         your latest changes to that file.
  213.                         Analogous to Turbo Pascal's Make and Build compile
  214.                         options, "Make index file(s)" will scan only those
  215.                         units that have been changed since the last index
  216.                         generation, while "Build index file(s)" will scan
  217.                         all units used by your program.
  218.  
  219.  
  220.   Getting Pop-Up Help:
  221.  
  222.   Apprentice's pop-up help is very similiar to the built-in context
  223.   sensitive help feature of Turbo Pascal's integrated environment. While you
  224.   are in the editor, place the cursor on the procedure or function name for
  225.   which you need help and press <Shift><F1>.  Apprentice will search the
  226.   index files for that name and, upon finding it, will pop up a help window.
  227.   The window will display the name of the unit containing the procedure or
  228.   function and the reference information for that procedure or function.
  229.   If the information does not all fit within the bounds of the help window,
  230.   you can scroll around using the four cursor movement keys.  Use <Tab> and
  231.   <Shift><Tab> to highlight the next and previous hot keywords, respectively.
  232.   While a hot keyword is highlighted, pressing <Enter> will cause Apprentice
  233.   to search its indexes for that keyword and display the new information
  234.   if it is found.  Pressing <Esc> will take you back to the Turbo Pascal
  235.   editor.
  236.  
  237.  
  238.  
  239. Tips, notes, etc.
  240. -----------------
  241.  
  242.   - Because Apprentice is meant to be used with Turbo Pascal's integrated
  243.     environment and is not very useful otherwise, you may wish make up a
  244.     batch file that installs Apprentice in memory, runs Turbo Pascal, and
  245.     then removes Apprentice from memory.  For example, the file "TP5.BAT"
  246.     might contain the following:
  247.  
  248.       TAP
  249.       TURBO
  250.       TAP /R
  251.  
  252.     Assuming DOS could find TAP.EXE and TURBO.EXE on the path, this batch
  253.     file would load and remove Apprentice automatically, and Apprentice
  254.     won't be sitting around in memory wasting RAM when you don't need it.
  255.  
  256.   - The Apprentice help window uses a "virtual window" to let you scroll
  257.     around in case your code/comments do not fit within the boundary of
  258.     the physical window.  Because the dimensions of this virtual window
  259.     are 126 characters by 48 lines, this limits the amount of comments
  260.     you can include.  If you exceed these limits in your source file, you
  261.     will not encounter any Apprentice errors -- you just won't be able
  262.     to view the extra information.
  263.  
  264.  
  265.  
  266. Trademarks
  267. ----------
  268.  
  269. IBM PC/XT/AT and PS/2 are registered trademarks of the International
  270. Business Machines Corporation.
  271.  
  272. MS-DOS is a registered trademark of Microsoft Corporation.
  273.  
  274. Borland and Turbo Pascal are registered trademarks of Borland International.
  275.  
  276.  
  277.  
  278. Copyright information
  279. ---------------------
  280.  
  281. Copyright (c) 1988 Cypress Systems, Inc.  All Rights Reserved.
  282.  
  283. This program is provided AS IS without any warranty, expressed or implied,
  284. including but not limited to fitness for a particular purpose.
  285.